<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Converting ECLiPSe data to C data
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot008.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot007.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot010.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc22">3.2</A>&nbsp;&nbsp;Converting ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data to C data</H2><UL>
<LI><A HREF="embroot009.html#toc15">Converting simple ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms to C data types</A>
<LI><A HREF="embroot009.html#toc16">Decomposing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</A>
</UL>


<A NAME="@default50"></A>
There are several aspects to examining the contents of a term. These
include decomposing compound terms such as lists and structures,
converting simple terms to C data types and testing the types of terms.<BR>
<BR>
The functions for decomposing and converting check that the type
is appropriate. If it is they return <CODE>EC_succeed</CODE> if not
they return a negative error code.<BR>
<BR>
<A NAME="toc15"></A>
<H3 CLASS="subsection"><A NAME="htoc23">3.2.1</A>&nbsp;&nbsp;Converting simple ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms to C data types</H3>
To convert from an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term to a C type you first have to
declare a variable with that type. For fixed size data types
(you can convert to <CODE>double</CODE>, <CODE>long</CODE> and <CODE>dident</CODE>
fixed size data types) you are responsible for allocating the
memory. For strings you declare a <CODE>char*</CODE> variable and
on conversion it will point to the internal ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> string.
<A NAME="@default51"></A><BR>
<BR>
In the following example we see how one can try to convert to
different types. Of course normally you will know what type
you are expecting so only one of these functions need be called.
<PRE CLASS="verbatim">
    EC_word term;
    double r;
    long i;
    EC_atom did;
    char *s;
    if (EC_succeed == term.is_double(&amp;d))
        cout &lt;&lt; d &lt;&lt; "\n";
    else if (EC_succeed == term.is_long(&amp;i))
        cout &lt;&lt; i &lt;&lt; "\n";
    else if (EC_succeed == term.is_atom(&amp;did))
        cout &lt;&lt; did.Name() &lt;&lt; "\n";
    else if (EC_succeed == term.is_string(&amp;s))
        cout &lt;&lt; s &lt;&lt; "\n";
    else
        cout &lt;&lt; "not a simple type\n";
</PRE>
The term is converted by the function which returns <CODE>EC_success</CODE>.
The functions that fail to convert will return a negative error number.<BR>
<BR>
<A NAME="@default52"></A>
<A NAME="@default53"></A>
Care has to be taken with strings, these pointers point to the internal
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> string which may move or be garbage collected during an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
execution. As a result if a string is to be kept permanently one should
copy it first.<BR>
<BR>
<A NAME="toc16"></A>
<H3 CLASS="subsection"><A NAME="htoc24">3.2.2</A>&nbsp;&nbsp;Decomposing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms</H3>
The function <CODE>ec_get_arg(index,term,&amp;subterm)</CODE> is used to get
the index'th subterm of a structure. The index varies from 1 to
arity of <CODE>term</CODE>. A list can also be decomposed this way, where
the head is at index 1 and the tail at index 2.
<A NAME="@default54"></A>
<A NAME="@default55"></A><BR>
<BR>
Below we see how we would write a function to find the nth element of
a list.
<PRE CLASS="verbatim">
    int nth(const int n,const EC_word list, EC_word&amp; el)
    {
        EC_word tail = list;
        for (int i=1, i&lt;n, i++)
            if (EC_fail == tail.arg(2,tail))
                return EC_fail;
        return tail.arg(1,el);
    }
</PRE>The above function actually is not limited to lists but could work
on any nested structure.<BR>
<BR>
<HR>
<A HREF="embroot008.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot007.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot010.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
